<html>
<head>
<title>Bug Submission</title>
</head>
<body>

<div id="apphead">
<h1><small>scons</small><br />Bug Submission</h1>

<p>
<strong>You must now
<a href="http://www.tigris.org/servlets/Login">log in</a>
to a <a href="http://www.tigris.org">tigris.org</a> account
before submitting a new bug report!</strong>
</p>

<p>
Bugs should be reported at the
<a href="http://scons.tigris.org/issues/enter_bug.cgi?component=scons&subcomponent=scons&issue_type=DEFECT">"Enter Issue" page</a>.
Please follow the <a href="bug-submission.html#guidelines">submission guidelines</a> below
to make sure your bug report contains the necessary information.
A more detailed set of <a href="bug-submission.html#steps">submission steps</a>
can be found below.
</p>

<p>
The above URL is set up for reporting a bug in SCons itself.
If you are reporting a problem in some other aspect of the SCons Project
(such as the documentation, or any of the web pages),
you must change the Subcomponent field of the submission form
to some other appropriate value.
</p>

</div>

<div class="h2 app" style="border-left: 0px" id="customcontent">

<h2 id="guidelines">Guidelines for a Useful Bug Report</h2>

<p>
Your bug will be much more likely to get diagnosed and fixed
if you supply all the necessary information to make it easy to do so.
</p>

<ul>
<li>
<strong>
<a href="http://www.tigris.org/servlets/Login">Log in</a>
to your tigris.org account before submitting a bug report
</strong>
<p>
If you do not already have a tigris.org account,
register for one at
<a href="http://www.tigris.org/servlets/Join">http://www.tigris.org/servlets/Join</a>.
</p>
<p>
We no longer accept anonymous bug reports,
due to spambot abuse of the open-door policy.
</p>
</li>
<li>
<strong>Specify the version of SCons in which you observed the problem</strong>
<p>
This helps avoid wasted time trying to pinpoint the version,
and also allows us to confirm if a later released version
has already fixed your problem.
</p>
</li>
<li>
<strong>Provide SConscript files or other configuration that reproduce the problem</strong>
<p>
If you can, simplify the configuration to just the
minimal subset that demonstrates the problem.
It's much harder to diagnose a problem
if the incorrect behavor is due to
one particular item out of a thousand
in a large configuration.
</p>
<p>
That said, it's most convenient if you can provide
an actual configuration (set of SConscript files
and/or other input files)
that can be downloaded and run to demonstrate the bug.
The easiest way is to attach a .tar.gz or .zip file
to the bug report.
Note that the tigris.org Issue Tracker
doesn't let you attach a file like this
when you initially submit the report.
You must first create the bug report,
and then attach a file to it as a separate step.
See below for the detailed steps.
</p>
<p>
If your problem is evident from a few specific SConscript lines,
it's perfectly acceptable just to
paste the lines into the Description field of the bug report.
</p>
</li>
<li>
<strong>Describe specifically the incorrect behavor you observed</strong>
<p>
It's best if you can cut and paste the output from SCons,
especially any error messages.
Otherwise,
Vague descriptions like,
"SCons errors out," or "Product XYZ doesn't compile"
are extremely difficult to diagnose,
because the different installed tools on someone else's system
may cause SCons to behave differently
and not demonstrate your bug.
</p>
</li>
<li>
<strong>Describe what you expected to happen</strong>
<p>
This isn't always obvious, especially if the
bug does not involve an SCons failure or error message.
Describing the behavior you expected
helps speed up the diagnosis.
</p>
</li>
</ul>

<h2 id="steps">Steps for Submitting a Bug Report</h2>

<p>
The following guides you step-by-step through the
process of submitting a new SCons bug report.
</p>

<p>
NOTE:  Creating a bug report with an attached file or files
(such as a .tar.gz or .zip file containing a sample configuration)
is a two-step process in the tigris.org Issue Tracker.
You must first create the bug report,
and then attach the file(s) in a separate step,
as described below.
</p>

<ul>
<li>
<strong><a href="http://www.tigris.org/servlets/Login">Log in</a> at tigris.org</strong>
<p>
If you do not already have a tigris.org account,
register for one at
<a href="http://www.tigris.org/servlets/Join">http://www.tigris.org/servlets/Join</a>.
</p>
<p>
We no longer accept anonymous bug reports,
due to spambot abuse of the open-door policy.
</p>
</li>
<li>
<strong>Go to the
<a href="http://scons.tigris.org/issues/enter_bug.cgi?component=scons&subcomponent=scons&issue_type=DEFECT">"Enter issue" page</a>
</strong>
<p>
By default, the "scons" subcomponent is selected;
if this bug is for a different subcomponent, select that instead.
</p>
</li>
<li>
<strong>Specify the version of SCons in which you found the bug</strong>
<p>
</p>
</li>
<li>
<strong>Specify the Subcomponent (if the bug is not in SCons itself)</strong>
<p>
The URL two steps above assumes that you're reporting
a bug in the behavior of SCons itself.
If you're reporting a problem in some other aspect of the SCons Project
(such as the documentation, or the packaging),
please change the Subcomponent field to reflect that.
</p>
</li>
<li>
<strong>Specify the Platform and OS</strong>
<p>
The Platform field is less important here
(SCons doesn't have many behavioral difference
due to different hardware platforms)
but the OS field is important.
</p>
</li>
<li>
<strong>Fill in a good Summary line describing the bug</strong>
<p>
This line is what shows up in summary reports,
so it should be descriptive but not too long.
Avoid overly-general things like "SCons error," etc.
</p>
</li>
<li>
<strong>Fill in the Description field</strong>
<p>
This is where you should go into detail
about the configuration,
the exact error you see,
what you expected to happen, etc.
When in doubt, include more information rather than less.
</p>
</li>
<li>
<strong>Press the "Submit issue" to submit your report</strong>
<p>
You will now receive a <tt>Posting issue</tt> page
that gives you the number of the issue you submitted.
</p>
</li>
<li>
<strong>If you have a .tar.gz, .zip or other file to attach:</strong>
<ul>
<li>
<strong>Click the "Attach a file to this issue" link</strong>
</li>
<li>
<strong>Fill in the "File" field with the path to the file you want to upload</strong>
(You can also do this through the <tt>Browse...</tt> button.)
</li>
<li>
<strong>Fill in the Description field</strong>
</li>
<li>
<strong>Click the "Submit" button</strong>
</li>
</ul>
</li>
</ul>

</div>

</body>
</html>
